ACH Internet Payment Guide using Payment Vault - For Online Payment Websites

Introduction

In this guide we will be walking you through how to create single and recurring payments initiated by an end user through the internet using the Payment Vault web service. Our objective will be to establish the basics by using specific ACH payment type examples, however the examples should provide you with the information needed to customize to your specific needs. Internet Payments are initiated and authorized via the internet by the end-user. ACH payments are those payments against a Checking or Savings bank account. If you have a customer facing online platform where users can login and initiate payments from their bank accounts, you will want to follow this guide for proper payment routing.

Getting Started

Here's what you'll do in this guide

Create a single ACH payment with custom data.
Create a recurring ACH payment resulting from user-initiated payment schedules in your platform.

note

How to determine when to use Single vs Recurring?

The best way to determine this is to consider how you are obtaining the on-screen ACH authorization from the user. If the user is authorizing each payment individually, then SaleFromBankAccount should be used. If the user is authorizing a payment once for the initial payment as well as future payments which will be made on a cadence by your system (monthly, quarterly, annually, etc), then RecurringSaleFromBankAccount should be used.

Prerequisites needed before continuing

You will want to obtain your test credentials in order to try any of the examples in this guide. You should have received these from your Implementation Coordinator.
Review the Authentication guide for an understanding on how to authenticate to the EPS web service. This guide will walk you through sending a test connection and test credentials to ensure you are able to authenticate before moving forward.
Review the Vaulting Customer and Account Data guide on how to create customers and accounts used in this guide.
Download the Payment Vault WSDL file from the Downloads menu

Create a single ACH payment with custom data workflow guide

For this guide we will walk through a hypothetical example where a customer is making a one-time payment of 25 dollars for purchasing a product that they have initiated through a customer facing website. We have given the product an ID of A1234 which we will track with the transaction. The customer will be a returning user which is authenticated in the payment site and their payment information has been previously vaulted with tokens called referenceIDs.

Step 1 The first thing that will need to occur is to capture the Required information needed to build the web request. Since this is Payment Vault we will be dealing with previously vaulted customers and accounts and will know what the reference ids are. For this example, we will say the customer has initiated a payment on our website and we have gathered the following information.
- Account reference id: ARI1234
- Amount: 25.00 purchase amount.
- Product ID: A1234 from product selection
Step 2 Using the collected information, we will populate a SaleFromBankAccount request in order to process this payment. The SaleFromBankAccount method is inherently an ACH debit transaction.
- Add the accountReferenceId. This is a token that represents the account information that was previously stored in the EPS system. This will be what the EPS system will use to pull the routing and account number for the actual payment.
- We will also add the productid they purchased to Field1 so it will be stored with the transaction and can be reported on in Transaction Reporting.
- Since this is an internet payment, we need to specify “Internet” as the “PaymentOrigin”.

Here is what our completed SaleFromBankAccount request will look like for this example.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pv="https://ssl.selectpayment.com/PV">
   <soapenv:Header>
      <pv:SecurityHeader>
         <pv:BinarySecurityToken>your security token here</pv:BinarySecurityToken>
      </pv:SecurityHeader>
   </soapenv:Header>
   <soapenv:Body>
    <pv:SaleFromBankAccount>
        <pv:storeId>0</pv:storeId>
        <pv:storeKey isNull="true" />
        <pv:entityId>your entityId</pv:entityId>
        <pv:locationId>your locationId</pv:locationId>
        <pv:accountReferenceId>ARI1234</pv:accountReferenceId>
        <pv:paymentOrigin>Internet</pv:paymentOrigin>
        <pv:notificationMethod>Merchant_Notify</pv:notificationMethod>
        <pv:Amount>25.00</pv:Amount>
        <pv:terminalNumber>__WebService</pv:terminalNumber>
        <pv:TransactionNumber>111</pv:TransactionNumber>
        <pv:Description></pv:Description>
        <pv:Field1>A1234</pv:Field1>
        <pv:Field2></pv:Field2>
        <pv:Field3></pv:Field3>
        <pv:clientIP></pv:clientIP>
        <pv:EffectiveDate>12-30-2010</pv:EffectiveDate>
    </pv:SaleFromBankAccount>
	</soapenv:Body>
</soapenv:Envelope>

Step 3 Once this request is sent to the endpoint, we should get a successful response and there are a few key items that are important to log with this response.
- ReferenceNumber - EPS generates this value for you to use for pulling reporting information on the transaction later. You will want to store this number with the transaction in your database.
- Success - indicates a successful transaction.
- Error - indicates if an error has occurred.
- ResponseCode - EPS code signifying result of the request.
- ActualDate - when the transaction was created in EPS.
- ResponseMessage - detailed description for the response code when applicable.

Here is what our successful response looks like for this example.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <SaleFromBankAccountResponse xmlns="https://ssl.selectpayment.com/PV">
            <SaleFromBankAccountResult>
                <ReferenceNumber>T:06N6Y1R7A2L</ReferenceNumber>
                <Success>true</Success>
                <Error>false</Error>
                <ResponseCode>Success</ResponseCode>
                <ActualDate>2010-12-30T00:00:00.0000000-06:00</ActualDate>
                <ResponseMessage/>
                <OriginatedAs>ACH</OriginatedAs>
            </SaleFromBankAccountResult>
        </SaleFromBankAccountResponse>
    </soap:Body>
</soap:Envelope>

Here is how the single payment example looks represented as a complete workflow diagram. Click on the method boxes to be taken to the specific API reference.

	Integrator Payment Flow	EPS Web Service Flow

	EPS Web Service

1.	Gather payment information from user online.
2.	Initiate the payment with SaleFromBankAccount using payment information gathered from user.
		Successful payment Key Data Elements: SaleFromBankAccountResponse ReferenceNumber = Unique number assigned to transaction by EPS Success = true Error = false ResponseCode = Success ResponseMessage = Additional information for response code if applicable
3.	For successful payments: store the ReferenceNumber along with your TransactionNumber from SaleFromBankAccount in your database display and log any results.
		Unsuccessful Payment Key Data Elements: SaleFromBankAccountResponse Success = false Error = true or false ResponseCode = See API Reference ResponseMessage = Additional information for response code if applicable
4	For Unsuccessful payments: display and log the error and responsecode as needed

Create a recurring ACH payment workflow guide

For this guide we will walk through a hypothetical example where a customer has setup a monthly recurring payment of 5 dollars for a service that they have initiated through a customer facing website. We will track the payment month and occurrence along with the invoice ID in custom fields. The customer will be a returning user which is authenticated in the payment site and their payment information has been previously vaulted with tokens called referenceIDs when they initially setup the schedule in the customer facing website.

Step 1 The first thing that will need to occur is to use the payment information generated by the recurring payment schedule setup by the user Required to build the web request. Since this is Payment Vault we will be dealing with previously vaulted customers and accounts and will know what the reference ids are. For this example, we will say the recurring schedule has generated a payment for October invoice ID RP1234 which is payment 10 of 12.
- Account reference id: ARI1234
- Amount: 5.00 monthly payment.
- InvoiceID: RP1234
- Recurring information: October 10/12
Step 2 Using the collected information, we will populate a RecurringSaleFromBankAccount request in order to process this payment. The RecurringSaleFromBankAccount method is inherently an ACH debit transaction.
- Add the accountReferenceId. This is a token that represents the account information that was previously stored in the EPS system. This will be what the EPS system will use to pull the routing and account number for the actual payment.
- We will also add the invoiceID RP123 to Field1 and recurring information October 10/12 to Field2 so it will be stored with the transaction and can be reported on in Transaction Reporting.
- Since this is an internet payment, we need to specify “Internet” as the “PaymentOrigin”.

Here is what our completed RecurringSaleFromBankAccount request will look like for this example.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pv="https://ssl.selectpayment.com/PV">
   <soapenv:Header>
      <pv:SecurityHeader>
         <pv:BinarySecurityToken>your security token here</pv:BinarySecurityToken>
      </pv:SecurityHeader>
   </soapenv:Header>
   <soapenv:Body>
    <pv:RecurringSaleFromBankAccount>
        <pv:storeId>0</pv:storeId>
        <pv:storeKey isNull="true" />
        <pv:entityId>your entityId</pv:entityId>
        <pv:locationId>your locationId</pv:locationId>
        <pv:accountReferenceId> ARI1234</pv:accountReferenceId>
        <pv:paymentOrigin>Internet<pv:/paymentOrigin>
        <pv:notificationMethod>Merchant_Notify</pv:notificationMethod>
        <pv:Amount>5.00</pv:Amount>
        <pv:terminalNumber>__WebService</pv:terminalNumber>
        <pv:TransactionNumber></pv:TransactionNumber>
        <pv:Description></pv:Description>
        <pv:Field1>RP1234</pv:Field1>
        <pv:Field2>October 10/12</pv:Field2>
        <pv:Field3></pv:Field3>
        <pv:clientIP></pv:clientIP>
        <pv:EffectiveDate>2-10-2021</pv:EffectiveDate>
        <pv:faceFeeType>Face</pv:faceFeeType>
        <pv:batchNumber></pv:batchNumber>
        <pv:bypassSmartDetect>0</pv:bypassSmartDetect>
    </pv:RecurringSaleFromBankAccount>
	</soapenv:Body>
</soapenv:Envelope>

Step 3 Once this request is sent to the endpoint, we should get a successful response and there are a few key items that are important to log with this response.
- ReferenceNumber - EPS generates this value for you to use for pulling reporting information on the transaction later. You will want to store this number with the transaction in your database.
- Success - indicates a successful transaction.
- Error - indicates if an error has occurred.
- ResponseCode - EPS code signifying result of the request.
- ActualDate - when the transaction was created in EPS.
- ResponseMessage - detailed description for the response code when applicable.

Here is what our successful response looks like for this example.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <RecurringSaleFromBankAccountResponse xmlns="https://ssl.selectpayment.com/PV">
            <RecurringSaleFromBankAccountResult>
                <ReferenceNumber>T:WNSNJ49MLA1</ReferenceNumber>
                <Success>true</Success>
                <Error>false</Error>
                <ResponseCode>Success</ResponseCode>
                <ActualDate>2021-02-10T00:00:00</ActualDate>
                <ResponseMessage/>
                <OriginatedAs>ACH</OriginatedAs>
            </RecurringSaleFromBankAccountResult>
        </RecurringSaleFromBankAccountResponse>
    </soap:Body>
</soap:Envelope>

Here is how the recurring payment example looks represented as a complete workflow diagram. Click on the method boxes to be taken to the specific API reference.

	Integrator Payment Flow	EPS Web Service Flow

	EPS Web Service

1.	Gather payment information generated from the recurring schedule.
2.	Initiate the payment with RecurringSaleFromBankAccount using payment information gathered from user.
		Successful payment Key Data Elements: RecurringSaleFromBankAccountResponse ReferenceNumber = Unique number assigned to transaction by EPS Success = true Error = false ResponseCode = Success ResponseMessage = Additional information for response code if applicable
3.	For Successful payments: store the ReferenceNumber along with your TransactionNumber from RecurringSaleFromBankAccount in your database display and log any results.
		Unsuccessful Payment Key Data Elements: RecurringSaleFromBankAccountResponse Success = false Error = true or false ResponseCode = See API Reference ResponseMessage = Additional information for response code if applicable
4	For Unsuccessful payments: display and log the error and responsecode as needed

Handling Errors and Failed Requests

Not all requests will be successful, so we will need to run through a few common errors you should be ready to handle.

Velocity error - Velocity declines will happen when one of the payment amount or count limits are exceeded by the transaction. It is important not to automatically retry the transaction as it will not succeed without being under the current limits. To handle this situation, store the velocity decline response with transaction details. Reach out through your normal support channels to discuss your velocity limits further.
Duplicate transaction - Duplicate transactions will be declined. Transactions are checked against our duplicate table which is a rolling 75 days of history and is checked against other transactions for the same merchant (entityID). It is important that transactions that receive a duplicate error are not automatically retried and there are two ways to handle it.
- The transaction is a true duplicate and will not need another attempt. Record the response and no further action is needed.
- You are certain that the transaction is not really a duplicate and need it to process. For WEB payments a duplicate is flagged when the Transaction Number is not unique. This means the Transaction Number value will need to change to something unique and resubmit the request.
Timeout waiting for response - Timeout waiting for response - Systems should be designed to wait 5 seconds for ACH transactions to receive a response before timing out. If a timeout occurs, you can attempt to query the system with one of the GetTransaction methods to verify if the transaction was received. If it was not the transaction can be resubmitted.

Next Steps

Customize the workflows to fit your specific business needs.
- You can apply the principles shown in these examples and customize the requests using the API Reference to suit your needs.
  - SDSaleFromBankAccount - used to create a same day ACH debit from a customer's checking or savings account. (Same Day ACH rules will apply, speak with your implementation coordinator or sales rep for more information.)
Review the API Reference
- This guide is just a starting point to show a common use case scenario for making internet payments. Please review the API Reference to see all APIs and their technical specifications.
Explore other guides
- We have other guides to show how to leverage our APIs in other common use cases so if this one doesn't cover what you are looking for, give another guide a try.
Get certified and move into production
- Ready to put your new code into production use? Refer to this process guide that explains our certification steps and how to contact us to get started.

Introduction​

Getting Started​

Create a single ACH payment with custom data workflow guide​

Create a recurring ACH payment workflow guide​

Handling Errors and Failed Requests​

Next Steps​